_o_u_t_p_u_t_U_s_a_g_e Specifies the mode in which the buffer will be used as
output; says how the image will be placed into the buffer
by a plug-in or application. The value is one of
bbbbuuuuffffOOOOuuuuttttppppuuuuttttDDDDiiiirrrreeeecccctttt, bbbbuuuuffffOOOOuuuuttttppppuuuuttttOOOOppppeeeennnnGGGGLLLL, bbbbuuuuffffOOOOuuuuttttppppuuuuttttmmmmoooovvvviiiieeee. No more
that one can be set.
_i_n_p_u_t_U_s_a_g_e Specifies the modes in which the buffer will be used as
input; says how the image will be read from the buffer and
used as input to a plug-in or application. The value is a
bitwise combination of one or more of: bbbbuuuuffffIIIInnnnppppuuuuttttDDDDiiiirrrreeeecccctttt,
bbbbuuuuffffIIIInnnnppppuuuuttttTTTTeeeexxxxttttuuuurrrreeee, bbbbuuuuffffIIIInnnnppppuuuuttttDDDDrrrraaaawwwwPPPPiiiixxxxeeeellllssss, bbbbuuuuffffIIIInnnnppppuuuuttttMMMMoooovvvviiiieeee. The
options set must include all of the different ways in which
this specific image will be used.
DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
These functions are used to prepare buffers before calling an image
processing plugin, and clean up after calling a plugin.
Image buffers for special effects require special handling because they
must support efficient access to OpenGL and image
compression/decompression. Because of this, they may reside in memory
that is shared with the graphics and compression device drivers. Setting
up a buffer before calling a plugin may involve cache flushing and image
reformatting. Similarly, after a plugin is called, cleanup may involve
restoring cache coherency and reformatting the image.
Every use of an image buffer must be preceeded by a setup call, and
succeeded by a cleanup call.
If an image buffer is to be used as input to a plugin,
ddddmmmmFFFFXXXXSSSSeeeettttuuuuppppIIIInnnnppppuuuuttttIIIImmmmaaaaggggeeeeBBBBuuuuffffffffeeeerrrr should be called before calling the plugin, and
ddddmmmmFFFFXXXXCCCClllleeeeaaaannnnuuuuppppIIIInnnnppppuuuuttttIIIImmmmaaaaggggeeeeBBBBuuuuffffffffeeeerrrr should be called after the plugin has
finished.
If an image buffer is to be used to store the output of a plugin,
ddddmmmmFFFFXXXXSSSSeeeettttuuuuppppOOOOuuuuttttppppuuuuttttIIIImmmmaaaaggggeeeeBBBBuuuuffffffffeeeerrrr should be called before the plugin is invoked,
and ddddmmmmFFFFXXXXCCCClllleeeeaaaannnnuuuuppppOOOOuuuuttttppppuuuuttttIIIImmmmaaaaggggeeeeBBBBuuuuffffffffeeeerrrr should be called afterward.
Usage bits must be supplied to ddddmmmmFFFFXXXXSSSSeeeettttuuuuppppOOOOuuuuttttppppuuuuttttIIIImmmmaaaaggggeeeeBBBBuuuuffffffffeeeerrrr that specify
both how the image will be generated (output usage) and how it will
later be used (input usage). The input usage must be specified at this
point so that the format of the data in the buffer will match the way it
will be used. If an application does not know how a buffer will be used,
it can use bbbbuuuuffffIIIInnnnppppuuuuttttAAAAllllllll as the input usage, but this may impair
performance.
It is acceptable to always use bbbbuuuuffffIIIInnnnppppuuuuttttAAAAllllllll when specifying input usage,
but doing so may slow things down. If your application does not have the
input usage available when calling ddddmmmmFFFFXXXXSSSSeeeettttuuuuppppOOOOuuuuttttppppuuuuttttIIIImmmmaaaaggggeeeeBBBBuuuuffffffffeeeerrrr, you can
give it bbbbuuuuffffIIIInnnnppppuuuuttttAAAAllllllll. If the input usage is known later, at the time when
the buffer is set up for input, ddddmmmmFFFFXXXXSSSSeeeettttuuuuppppIIIInnnnppppuuuuttttIIIImmmmaaaaggggeeeeBBBBuuuuffffffffeeeerrrrWWWWiiiitttthhhhUUUUssssaaaaggggeeee may be
used. This will enable the some optimizations, but may not be as
efficient as specifying the input usage when the buffer is set up for
output.
If an application needs to read or write the contents of an image buffer
directly, it should treat itself as a plugin that uses direct access.
For example, to place an image in a buffer, call
ddddmmmmFFFFXXXXSSSSeeeettttuuuuppppOOOOuuuuttttppppuuuuttttIIIImmmmaaaaggggeeeeBBBBuuuuffffffffeeeerrrr with bbbbuuuuffffOOOOuuuuttttppppuuuuttttDDDDiiiirrrreeeecccctttt, use
ddddmmmmFFFFXXXXSSSSeeeettttuuuuppppSSSSccccaaaannnnlllliiiinnnneeeeBBBBuuuuffffffffeeeerrrr to get a pointer to the buffer, store the pixels,
and finally call ddddmmmmFFFFXXXXCCCClllleeeeaaaannnnuuuuppppOOOOuuuuttttppppuuuuttttIIIImmmmaaaaggggeeeeBBBBuuuuffffffffeeeerrrr.
Normally, calling ddddmmmmFFFFXXXXSSSSeeeettttuuuuppppOOOOuuuuttttppppuuuuttttIIIImmmmaaaaggggeeeeBBBBuuuuffffffffeeeerrrr will discard any previous
contents of the buffer. In one case, though, the contents of the buffer
are guaranteed to be preserved: if a buffer has been set up for direct
input, setting it up for direct output will preserve the contents of the
